{
 "cells": [
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "These examples will illustrate only some of the functionality that :func:`relplot` is capable of. For more information, consult the examples for :func:`scatterplot` and :func:`lineplot`, which are used when ``kind=\"scatter\"`` or ``kind=\"line\"``, respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "hide"
    ]
   },
   "outputs": [],
   "source": [
    "import seaborn as sns\n",
    "import matplotlib.pyplot as plt\n",
    "sns.set_theme(style=\"ticks\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "To illustrate ``kind=\"scatter\"`` (the default style of plot), we will use the \"tips\" dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "tips = sns.load_dataset(\"tips\")\n",
    "tips.head()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Assigning ``x`` and ``y`` and any semantic mapping variables will draw a single plot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", hue=\"day\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Assigning a ``col`` variable creates a faceted figure with multiple subplots arranged across the columns of the grid:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", hue=\"day\", col=\"time\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Different variables can be assigned to facet on both the columns and rows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", hue=\"day\", col=\"time\", row=\"sex\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When the variable assigned to ``col`` has many levels, it can be \"wrapped\" across multiple rows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=tips, x=\"total_bill\", y=\"tip\", hue=\"time\", col=\"day\", col_wrap=2)"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Assigning multiple semantic variables can show multi-dimensional relationships, but be mindful to avoid making an overly-complicated plot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=tips, x=\"total_bill\", y=\"tip\", col=\"time\",\n",
    "    hue=\"time\", size=\"size\", style=\"sex\",\n",
    "    palette=[\"b\", \"r\"], sizes=(10, 100)\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "When there is a natural continuity to one of the variables, it makes more sense to show lines instead of points. To draw the figure using :func:`lineplot`, set ``kind=\"line\"``. We will illustrate this effect with the \"fmri dataset:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fmri = sns.load_dataset(\"fmri\")\n",
    "fmri.head()"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Using ``kind=\"line\"`` offers the same flexibility for semantic mappings as ``kind=\"scatter\"``, but :func:`lineplot` transforms the data more before plotting. Observations are sorted by their ``x`` value, and repeated observations are aggregated. By default, the resulting plot shows the mean and 95% CI for each unit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri, x=\"timepoint\", y=\"signal\", col=\"region\",\n",
    "    hue=\"event\", style=\"event\", kind=\"line\",\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The size and shape of the figure is parametrized by the ``height`` and ``aspect`` ratio of each individual facet:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(\n",
    "    data=fmri,\n",
    "    x=\"timepoint\", y=\"signal\",\n",
    "    hue=\"event\", style=\"event\", col=\"region\",\n",
    "    height=4, aspect=.7, kind=\"line\"\n",
    ")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "The object returned by :func:`relplot` is always a :class:`FacetGrid`, which has several methods that allow you to quickly tweak the title, labels, and other aspects of the plot:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "g = sns.relplot(\n",
    "    data=fmri,\n",
    "    x=\"timepoint\", y=\"signal\",\n",
    "    hue=\"event\", style=\"event\", col=\"region\",\n",
    "    height=4, aspect=.7, kind=\"line\"\n",
    ")\n",
    "(g.map(plt.axhline, y=0, color=\".7\", dashes=(2, 1), zorder=0)\n",
    "  .set_axis_labels(\"Timepoint\", \"Percent signal change\")\n",
    "  .set_titles(\"Region: {col_name} cortex\")\n",
    "  .tight_layout(w_pad=0))"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "It is also possible to use wide-form data with :func:`relplot`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "flights_wide = sns.load_dataset(\"flights\").pivot(\"year\", \"month\", \"passengers\")"
   ]
  },
  {
   "cell_type": "raw",
   "metadata": {},
   "source": [
    "Faceting is not an option in this case, but the plot will still take advantage of the external legend offered by :class:`FacetGrid`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sns.relplot(data=flights_wide, kind=\"line\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "seaborn-py38-latest",
   "language": "python",
   "name": "seaborn-py38-latest"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
